名前¶

mbrtowc - マルチバイト列をワイド文字に変換する

書式¶

#include <wchar.h>

size_t mbrtowc(wchar_t *pwc, const char *s, size_t n, mbstate_t *ps);

説明¶

この関数が用いられる場合、通常 s が NULL でなく pwc も NULL で ない。この場合は、 mbrtowc() 関数は s から始まる最大 n バイトの マルチバイト文字を検査して、次の完全なマルチバイト文字列を取り出し、 それをワイド文字に変換して *pwc に格納する。 同時にシフト状態 *ps を更新する。変換したワイド文字が L'\0' で なければ、s から消費するバイト数を返す。 変換したワイド文字が L'\0' の場合にはシフト状態 *ps を 初期状態に戻して 0 を返す。

s から始まる n バイトが完全なマルチバイト文字を含んでいない 場合には、 mbrtowc() は (size_t) -2 を返す。 マルチバイト文字列に冗長なシフトシーケンスが含まれていると、 n >= MB_CUR_MAX の時にもこのようなことが起こりえる。

s から始まるマルチバイト文字列が、次の完全な文字の前に 不正なマルチバイト列を含んでいる場合には、 mbrtowc() は (size_t) -1 を返し、errno に EILSEQ を設定する。 この場合は *ps への影響は未定義である。

s が NULL でなく pwc が NULL の場合は mbrtowc() 関数は 上記と同様に動作するが、変換したワイド文字はメモリには書き込まれない。

puts *ps in the initial state and returns 0. 三番目の場合として s が NULL の場合、 pwc と n は 無視される。 *ps が表現する変換状態が不完全なマルチバイト文字変換を示している場合は、 mbrtowc() 関数は (size_t) -1 を返し、 errno に EILSEQ をセットし、 *ps は未定義状態のままにする。 さもなければ、 mbrtowc() 関数は *ps を初期状態にして 0 を返す。

上記の全ての場合において、ps が NULL ポインターならば代わりに mbrtowc 関数のみが使用する静的で名前のない状態が使用される。 さもなければ、*ps は有効な mbstate_t オブジェクトで なければならない。 mbstate_t オブジェクトである a はゼロで埋めることによって 初期状態に初期化できる。以下に例を示す。

memset(&a, 0, sizeof(a));

返り値¶

L'\0' 以外のワイド文字を認識した場合には mbrtowc() 関数は s から始まるマルチバイト列から解析したバイト数を返す。 L'\0' ワイド文字を認識した場合には 0 を返す。 不正なマルチバイト列に遭遇した場合には (size_t) -1 を返し、 errno に EILSEQ を設定する。完全なマルチバイト文字を 解析できなかった場合には (size_t) -2 を返し n を増加させる必要があることを示す。

準拠¶

C99.

注意¶

mbrtowc() の動作は現在のロケールの LC_CTYPE カテゴリに依存している。

関連項目¶

mbsrtowcs(3)